TypeScript를 활용한 Shapefile 지리공간 데이터 분석 및 활용 1

1. 서론

ESRI Shapefile은 1990년대 초 ArcView GIS 소프트웨어와 함께 소개된 이래, 지리공간 벡터 데이터 포맷의 사실상 업계 표준(de facto standard)으로 자리 잡았다.1 이 포맷은 포인트(points), 라인(lines), 폴리곤(polygons)과 같은 지리적 피처(feature)의 기하학적 위치 정보(geometry)와 관련 속성 정보(attribute)를 저장하는 데 사용된다.3 Shapefile의 핵심적인 설계 특징 중 하나는 위상(topology) 정보를 저장하지 않는다는 점이다. 이는 데이터 구조의 복잡성을 낮추어 렌더링 및 편집 속도를 향상시키는 장점으로 작용했으며, 다양한 GIS 소프트웨어 간 데이터 교환을 위한 주요 포맷으로 빠르게 채택되는 배경이 되었다.2

그러나 Shapefile이 설계된 시대의 컴퓨팅 환경과 현대의 개발 패러다임 사이에는 상당한 간극이 존재한다. 현대의 웹 및 서버 애플리케이션은 잘 정의된 단일 데이터 구조(예: JSON)를 기반으로 API를 통해 상태 없이(stateless) 통신하는 아키텍처를 선호한다. 반면, Shapefile은 단일 파일이 아닌, 최소 세 개의 필수 파일—.shp, .shx, .dbf—로 구성된 파일 집합이라는 근본적인 차이를 가진다.1 이러한 다중 파일 구조는 데이터 관리의 복잡성을 초래하며, 전송이나 보관 과정에서 파일 하나가 누락되거나 파일명의 접두사가 일치하지 않을 경우 전체 데이터셋이 손상되는 본질적인 취약점을 내포한다.6 이는 단순히 기술적인 파싱 문제를 넘어, 파일 시스템에 의존적인 레거시 데이터 모델과 현대적인 API 기반 아키텍처 간의 “임피던스 불일치(impedance mismatch)“를 야기하는 구조적 문제이다.

더 나아가 Shapefile 포맷은 여러 기술적 한계를 안고 있다. 속성 테이블의 필드 이름은 최대 10자로 제한되며, .shp와 .dbf 파일의 크기는 각각 2GB를 초과할 수 없다.1 또한, 지원하는 데이터 타입이 제한적이고 유니코드(Unicode) 지원이 미흡하여 다국어 환경에서 문제를 일으킬 수 있다.1 이러한 제약들은 대규모의 복잡한 데이터를 다루는 현대 애플리케이션의 요구사항과 정면으로 배치된다.

본 안내서는 TypeScript 개발자가 이러한 레거시 포맷의 구조적 복잡성과 한계를 명확히 이해하고, 이를 현대적인 개발 환경에서 안정적이고 효율적으로 처리하는 방법을 제시하는 것을 목표로 한다. 이를 위해 먼저 Shapefile을 구성하는 핵심 파일들의 바이너리 구조를 심층적으로 분석하여 포맷 자체에 대한 근본적인 이해를 제공한다. 이후, 현재 사용 가능한 주요 JavaScript/TypeScript 라이브러리들을 기능, API 설계, 성능, TypeScript 지원 수준 등의 기준으로 비교 분석하여 각기 다른 요구사항에 맞는 최적의 도구를 선택할 수 있는 기준을 제시한다. 최종적으로, 가장 범용적이고 개발자 친화적인 라이브러리인 shpjs를 사용하여 Shapefile을 현대 웹 GIS의 표준인 GeoJSON (RFC 7946)으로 변환하고, 변환된 데이터를 타입-세이프(type-safe) 방식으로 활용하는 실용적인 코드 예제를 통해 구체적인 구현 전략을 상세히 다룰 것이다. 이 안내서는 단순한 사용법 안내를 넘어, 레거시 데이터 소스를 현대 애플리케이션 스택에 안전하게 통합하기 위한 아키텍처 패턴 가이드 역할을 수행하고자 한다.

2. Shapefile 포맷의 구조적 이해

Shapefile의 안정적인 처리를 위해서는 그 내부 바이너리 구조에 대한 깊이 있는 이해가 필수적이다. 각 파일은 고유한 역할을 수행하며, 이들의 유기적인 관계를 파악하는 것이 파서(parser)를 구현하거나 디버깅할 때 핵심이 된다.

2.1 핵심 구성 파일의 역할과 관계

Shapefile은 단일 파일이 아니라 동일한 파일 이름을 공유하고 확장자만 다른 파일들의 집합이다.1 이 중 가장 핵심적인 세 가지 파일은 다음과 같다.

• .shp (Main File): 지리적 피처의 지오메트리, 즉 좌표 데이터를 저장하는 주 파일이다. 이 파일은 가변 길이 레코드(variable-length records)로 구성되어 있어 각 피처의 복잡성에 따라 레코드 크기가 달라진다.1

• .dbf (dBASE Table): 각 지오메트리에 대한 속성 정보를 저장하는 파일로, dBASE IV 형식을 따른다.1

.shp 파일의 각 레코드와 .dbf 파일의 각 레코드는 파일 내 순서에 기반한 엄격한 일대일 관계를 맺는다. 즉, .shp 파일의 n번째 지오메트리는 .dbf 파일의 n번째 레코드에 해당하는 속성 정보를 가진다.5

• .shx (Index File): .shp 파일의 가변 길이 레코드에 대한 빠른 임의 접근(random access)을 가능하게 하는 인덱스 파일이다.4 각 레코드의 시작 위치(offset)와 길이를 저장하고 있어, .dbf 파일에서 특정 속성 조건으로 레코드를 필터링한 후, 해당 레코드 번호를 이용해 .shp 파일에서 직접 지오메트리 데이터를 신속하게 찾아낼 수 있다.4 여기서 중요한 점은 .shx 파일이 공간 인덱스(spatial index)가 아니라, 단순히 파일 내 레코드의 위치를 가리키는 오프셋 인덱스라는 것이다.8

이 세 파일은 반드시 함께 존재해야 하며, 파일명의 접두사(예: roads)가 동일해야 한다. 하나라도 누락되거나 이름이 다를 경우, 대부분의 GIS 소프트웨어나 라이브러리는 데이터를 정상적으로 읽지 못한다.

2.2 .shp 파일의 바이너리 구조

.shp 파일은 100바이트의 고정 길이 파일 헤더와 그 뒤를 잇는 다수의 가변 길이 레코드로 구성된다. 이 파일의 구조를 이해할 때 가장 중요한 개념 중 하나는 혼합된 엔디안(mixed-endian) 아키텍처이다.

• 파일 헤더 (File Header): 파일의 가장 앞부분에 위치하며, 전체 파일에 대한 핵심 메타데이터를 담고 있다. 주요 필드는 파일 코드(항상 9994), 파일 전체 길이, 버전(항상 1000), Shape 유형, 그리고 모든 지오메트리를 포함하는 최소 경계 상자(Minimum Bounding Box, MBR) 등이다.3

이 헤더 구조의 특이점은 필드에 따라 바이트 순서(byte order, endianness)가 다르다는 것이다. 파일 전체 길이와 같이 파일 관리에 관련된 정수는 빅 엔디안(Big Endian)으로 저장되는 반면, Shape 유형이나 좌표 데이터와 같은 지오메트리 관련 데이터는 리틀 엔디안(Little Endian)으로 저장된다.3 이러한 설계는 역사적인 배경에서 기인한 것으로 추정된다. 빅 엔디안은 과거 유닉스(UNIX) 기반 워크스테이션에서 주로 사용되었고, 리틀 엔디안은 인텔 x86 아키텍처 기반의 데스크톱 PC에서 표준으로 자리 잡았다. Shapefile 포맷은 이 두 아키텍처가 공존하던 과도기에 설계되었거나, 서버(빅 엔디안)와 클라이언트(리틀 엔디안) 간의 플랫폼 호환성을 염두에 두었을 가능성이 있다. TypeScript 개발자에게 이는 중요한 실무적 함의를 가진다. 바이너리 데이터를 ArrayBuffer로 읽을 때, 단순히 Uint32Array와 같은 타입 배열로 데이터를 해석해서는 안 된다. 반드시 DataView 객체를 사용하여 각 필드의 오프셋과 엔디안 설정을 명시적으로 지정하여 읽어야 한다 (getUint32(offset, false)는 빅 엔디안, getUint32(offset, true)는 리틀 엔디안). 이 규칙을 따르지 않으면 완전히 잘못된 값을 읽게 된다.

표 1:.shp 파일 헤더 구조 (100바이트) 3

• 레코드 (Records): 파일 헤더 다음에는 각 지오메트리 피처에 해당하는 가변 길이 레코드들이 순차적으로 나열된다. 각 레코드는 8바이트의 레코드 헤더와 실제 지오메트리 데이터가 담긴 레코드 내용으로 구성된다.

• 레코드 헤더: 8바이트 고정 길이며, 레코드 번호(1부터 시작)와 레코드 내용의 길이(16비트 워드 단위)를 빅 엔디안으로 저장한다. 이 길이는 Shape 유형을 포함한 순수 지오메트리 데이터의 크기를 나타낸다.3

• 레코드 내용: 레코드 내용의 첫 4바이트는 해당 지오메트리의 Shape 유형을 리틀 엔디안 정수 값으로 명시한다. 이 값에 따라 뒤따르는 좌표 데이터의 구조가 결정된다.3

• Shape 유형별 데이터 레이아웃: 모든 Shapefile은 단일한 유형의 지오메트리만 포함해야 한다 (Null Shape 제외). 주요 Shape 유형과 그 값은 아래 표와 같다.

표 2: 주요 Shape 유형 및 값 3

예를 들어, PolyLine과 Polygon은 유사한 구조를 가진다. 먼저 전체 경계 상자(Bounding Box), 파트(parts)의 수, 전체 정점(points)의 수를 저장한다. 그 다음, 각 파트가 시작되는 정점의 인덱스를 담은 배열이 오고, 마지막으로 모든 파트의 모든 정점 좌표(X, Y)가 연속적으로 저장된다.[3] 이 구조는 복잡한 다중 파트 지오메트리를 효율적으로 표현할 수 있게 한다.

2.3 .shx 및 .dbf 파일 구조

• .shx 파일: 이 파일은 .shp 파일의 빠른 탐색을 돕는다. 구조는 매우 단순하다. .shp 파일과 동일한 100바이트 헤더로 시작하며, 그 뒤로 각 레코드에 대한 8바이트짜리 인덱스 정보가 고정 길이로 이어진다.

표 3:.shx 파일 레코드 구조 (8바이트) 3

이 오프셋 정보를 이용하면 .shp 파일을 처음부터 순차적으로 읽지 않고도 특정 레코드로 즉시 이동할 수 있다.

• .dbf 파일: 속성 데이터는 dBASE IV 표준을 따르는 .dbf 파일에 저장된다. 이 파일 포맷은 Shapefile보다 더 오래된 유산으로, 그 자체로 복잡한 구조를 가진다.

• 헤더: 파일의 첫 부분에 위치하며, dBASE 버전, 마지막 업데이트 날짜, 레코드의 총 개수, 헤더의 바이트 길이, 각 레코드의 바이트 길이 등의 정보를 포함한다.1

• 필드 서술자 (Field Descriptors): 헤더 바로 다음에 각 필드(열)에 대한 정보가 32바이트씩 나열된다. 각 서술자는 필드 이름(ASCII, 최대 10바이트), 필드 타입(문자 ‘C’, 숫자 ‘N’, 날짜 ‘D’ 등), 필드 길이, 소수점 자릿수 등의 정보를 담고 있다.1

• 데이터 레코드: 모든 필드 서술자 목록이 끝난 후, 실제 데이터 레코드들이 순차적으로 저장된다. 각 레코드는 헤더에 명시된 고정 길이를 가지며, 첫 번째 바이트는 레코드의 유효 상태를 나타내는 삭제 플래그(공백 0x20은 유효, 별표 0x2A는 삭제)로 사용된다.

.dbf 파일은 그 자체로 파싱하기 까다로운 레거시 포맷이다. 필드 타입이 제한적이고, 문자 인코딩 정보가 파일 내에 표준적으로 포함되지 않아 다국어 처리 시 문제가 발생할 수 있다. 이 때문에 Shapefile을 다루는 많은 라이브러리들은 .dbf 파싱을 위한 별도의 모듈을 포함하고 있다.

3. TypeScript 환경을 위한 Shapefile 처리 라이브러리 분석

TypeScript 환경에서 Shapefile을 처리하기 위해 여러 오픈소스 라이브러리가 존재한다. 이들은 각기 다른 설계 철학과 장단점을 가지고 있어, 프로젝트의 요구사항에 따라 적절한 라이브러리를 선택하는 것이 중요하다. npm 생태계에서 이러한 라이브러리들의 등장은 Shapefile 포맷의 내재된 결함을 해결하려는 개발자 커뮤니티의 성숙한 반응을 보여준다. 초기 라이브러리들은 기본적인 파싱 기능에 집중했지만, 후속 라이브러리들은 개발자 경험(DX), 특정 병목 현상에 대한 성능 최적화, 다양한 JavaScript 실행 환경을 위한 통합 API 등을 놓고 경쟁하며 발전해왔다.

3.1 주요 라이브러리 소개 및 선택 기준

주요 라이브러리 세 가지를 중심으로 분석한다.

• shpjs: 현재 가장 널리 사용되는 범용 라이브러리로, 사용 편의성에 중점을 둔다. ZIP 아카이브, 원격 URL, ArrayBuffer 등 다양한 형태의 입력을 단일 함수로 처리하여 GeoJSON으로 변환하는 고수준 API를 제공한다.9 이 라이브러리는 Shapefile의 다중 파일 구조로 인한 불편함을 효과적으로 추상화하여 개발자가 데이터 처리에만 집중할 수 있도록 돕는다. GitHub 리포지토리 이름은

shapefile-js이지만 npm에 등록된 패키지 이름은 shpjs이므로 혼동하지 않도록 주의해야 한다.10

• shapefile: D3.js의 창시자인 Mike Bostock이 개발한 라이브러리로, 스트리밍 파싱(streaming parsing)에 특화되어 있다.12 이 라이브러리는 대용량 Shapefile을 메모리에 한 번에 모두 로드하지 않고, 레코드 단위로 순차적으로 읽어 처리할 수 있게 해준다. 이 방식은 메모리 사용량을 최소화해야 하는 서버 측 배치(batch) 작업이나 메모리가 제한된 환경에서 매우 유리하다.12 저수준 제어와 메모리 효율성을 중시하는 개발자에게 적합하다.

• shp-to-geojson: shpjs와 shapefile의 대안으로 등장한 라이브러리다. 더 직관적인 API를 표방하며, 특히 속성 필드가 많은 .dbf 파일을 파싱할 때 높은 성능을 보인다고 주장한다.14 Node.js와 브라우저 환경에서 동일한 API를 제공하여 코드 재사용성을 높인다는 점을 장점으로 내세운다.14 이는 특정 성능 병목 현상을 해결하고 API의 직관성을 개선하려는 시도라고 볼 수 있다.

라이브러리 선택 시에는 다음과 같은 기준을 종합적으로 고려해야 한다.

• API 추상화 수준: shpjs와 같이 모든 복잡성을 감춘 고수준 API가 필요한가, 아니면 shapefile처럼 메모리 제어를 위한 저수준 스트리밍 API가 필요한가?

• 실행 환경: Node.js 서버 환경인가, 아니면 사용자 상호작용이 중요한 브라우저 환경인가?

• 성능 요구사항: 처리 속도가 중요한가, 아니면 메모리 사용량 최소화가 더 중요한가?

• TypeScript 지원: 공식적인 타입 정의(@types 패키지)가 제공되어 타입-세이프한 개발이 용이한가?

• 프로젝트 활성도: 라이브러리가 최근까지 유지보수되고 있으며, 커뮤니티 지원이 활발한가?

3.2 라이브러리 비교 분석

각 라이브러리의 특징을 구체적으로 비교하면 다음과 같다.

• API 설계: shpjs는 async/await와 함께 사용하기 좋은 Promise 기반의 단일 함수 API(await shp(source))를 제공하여 매우 간결하다.10 반면, shapefile은 open() 메서드로 소스(source) 객체를 생성한 후, source.read() 메서드를 반복적으로 호출하여 데이터를 읽는 스트리밍 이터레이터(iterator) 패턴을 채택하고 있다.12 이는 더 많은 제어권을 제공하지만 코드의 복잡성은 증가한다.

• TypeScript 지원: shpjs와 shapefile 모두 DefinitelyTyped 저장소를 통해 각각 @types/shpjs 15와 @types/shapefile 16 타입 정의 패키지를 제공한다. 따라서 두 라이브러리 모두 TypeScript 프로젝트에 원활하게 통합할 수 있다.

• 기능 및 제약사항: shpjs의 중요한 기능 중 하나는 .prj 파일이 존재할 경우, 이를 해석하여 좌표계를 표준 WGS 84(EPSG:4326)로 자동 재투영(reprojection)을 시도한다는 점이다.9 또한, 문자 인코딩 정보를 담은 .cpg 파일 처리도 명시적으로 지원하여 다국어 속성 데이터의 파손을 방지한다.10 반면, shapefile 라이브러리는 공식적으로 .prj 파일을 파싱하거나 좌표계 변환을 지원하지 않는다고 명시하고 있어, 재투영이 필요한 경우 개발자가 직접 외부 라이브러리(예: proj4js)를 사용하여 처리해야 한다.12

• 성능: shp-to-geojson의 자체 벤치마크 결과에 따르면, 속성 데이터가 많은(예: 40개 속성을 가진 3,000개 폴리곤) Shapefile을 처리할 때 shpjs나 shapefile보다 월등히 빠른 성능을 보인다.14 이는 .dbf 파일 파싱 로직에 최적화가 이루어졌음을 시사한다. 그러나 속성이 적은 데이터의 경우 성능 차이는 미미하다. 메모리 사용량 측면에서는, 파일 크기가 기가바이트 단위로 매우 클 경우 shapefile의 스트리밍 방식이 가장 압도적인 효율성을 제공한다.

이러한 분석을 종합하면, 각 라이브러리는 특정 문제 해결에 초점을 맞춰 진화해왔음을 알 수 있다. shapefile은 원시적인 파싱 능력과 메모리 효율성에, shpjs는 개발자 편의성과 사용성에, shp-to-geojson은 특정 상황에서의 처리 속도 최적화에 중점을 둔다.

표 4: 주요 Shapefile 처리 라이브러리 비교 9

이 비교표는 개발자가 자신의 프로젝트 요구사항에 가장 적합한 도구를 신속하게 식별할 수 있는 의사결정 매트릭스 역할을 한다. 예를 들어, “브라우저에서 사용자가 업로드한 ZIP 파일을 처리해야 한다“면 shpjs가 최적의 선택이며, “서버에서 수십 기가바이트 크기의 파일을 처리해야 한다“면 shapefile이 유일한 대안일 수 있다.

4. shpjs를 활용한 Shapefile 데이터 처리 실습

앞선 분석을 바탕으로, 대부분의 웹 애플리케이션 시나리오에서 가장 균형 잡힌 선택지인 shpjs를 사용하여 Shapefile을 처리하는 구체적인 방법을 알아본다. shpjs의 API는 Shapefile의 다중 파일 구조로 인한 복잡성을 우아하게 해결하며, 다양한 입력 형식을 일관된 방식으로 처리할 수 있도록 설계되었다.

4.1 개발 환경 설정

먼저, TypeScript 기반의 Node.js 프로젝트를 설정하고 필요한 패키지를 설치한다.

1. 프로젝트 초기화 및 TypeScript 설정:

mkdir shapefile-ts-project && cd shapefile-ts-project
npm init -y
npm install typescript ts-node --save-dev
npx tsc --init

tsconfig.json 파일에서 target을 es2020 이상으로, module을 commonjs로 설정하는 것이 일반적이다.

2. 필수 패키지 설치:

shpjs 라이브러리를 설치한다.

npm install shpjs

3. 타입 정의 패키지 설치:

TypeScript의 타입 시스템을 최대한 활용하기 위해 shpjs와 결과물인 GeoJSON에 대한 타입 정의 파일을 설치한다.

npm install @types/node @types/shpjs @types/geojson --save-dev

@types/shpjs는 shp 함수의 시그니처와 반환 타입을 제공하여 코드 작성 시 타입 추론과 자동 완성을 가능하게 한다.15

@types/geojson은 변환된 GeoJSON 객체(FeatureCollection, Feature, Geometry 등)를 타입-세이프하게 다루기 위해 필수적이다.

4.2 데이터 소스 유형별 파싱

shpjs는 다양한 데이터 소스를 유연하게 처리할 수 있다. 각 시나리오별 예제 코드는 다음과 같다.

• 로컬 ZIP 아카이브 버퍼 처리 (Node.js)

가장 일반적이고 안정적인 방법은 모든 Shapefile 구성 요소(.shp, .shx, .dbf 및 선택적 .prj, .cpg)를 단일 ZIP 파일로 압축하여 처리하는 것이다. Node.js의 fs 모듈을 사용하여 ZIP 파일을 Buffer로 읽고 shp 함수에 전달한다.

import * as fs from 'fs/promises';
import shp from 'shpjs';
import { FeatureCollection } from 'geojson';

async function parseZipFromBuffer(filePath: string): Promise<void> {
try {
console.log(`Reading file from: ${filePath}`);
const zipBuffer: Buffer = await fs.readFile(filePath);

console.log('Parsing shapefile...');
const geojson: shp.FeatureCollectionWithFilename | shp.FeatureCollectionWithFilename = await shp(zipBuffer);

// ZIP 파일 내 Shapefile이 하나일 경우 FeatureCollection, 여러 개일 경우 배열이 반환됨
const featureCollections = Array.isArray(geojson)? geojson : [geojson];

featureCollections.forEach((collection: shp.FeatureCollectionWithFilename) => {
console.log(`Successfully parsed: ${collection.fileName}`);
console.log(`Number of features: ${collection.features.length}`);

// 첫 번째 피처의 속성 정보 출력
if (collection.features.length > 0) {
console.log('Properties of the first feature:', collection.features.properties);
}
});

} catch (error) {
console.error('An error occurred:', error);
}
}

// 예제 실행: 'data/my_shapefile.zip' 파일이 있다고 가정
parseZipFromBuffer('data/my_shapefile.zip');

• 브라우저에서 사용자 업로드 ZIP 파일 처리

브라우저 환경에서는 HTML <input type="file"> 엘리먼트를 통해 사용자가 선택한 ZIP 파일을 ArrayBuffer로 변환하여 shp 함수에 전달한다.

// 이 코드는 React 컴포넌트나 순수 JavaScript 환경에서 사용될 수 있다.
import shp from 'shpjs';
import { FeatureCollection } from 'geojson';

const handleFileChange = async (event: React.ChangeEvent<HTMLInputElement>) => {
const files = event.target.files;
if (!files || files.length === 0) {
return;
}
const file = files;

try {
const arrayBuffer = await file.arrayBuffer();
const geojson = await shp(arrayBuffer) as FeatureCollection; // 타입 단언 사용

console.log('GeoJSON data loaded:', geojson);
console.log(`Number of features: ${geojson.features.length}`);
// 이후 지도에 렌더링하거나 상태(state)에 저장하는 로직 수행
} catch (error) {
console.error('Error parsing shapefile:', error);
}
};

// JSX 예시
// <input type="file" accept=".zip" onChange={handleFileChange} />
const file = files;

try {
const arrayBuffer = await file.arrayBuffer();
const geojson = await shp(arrayBuffer) as FeatureCollection; // 타입 단언 사용

console.log('GeoJSON data loaded:', geojson);
console.log(`Number of features: ${geojson.features.length}`);
// 이후 지도에 렌더링하거나 상태(state)에 저장하는 로직 수행
} catch (error) {
console.error('Error parsing shapefile:', error);
}
};

// JSX 예시
// <input type="file" accept=".zip" onChange={handleFileChange} />

• 원격 URL을 통한 데이터 로딩

shp 함수에 .zip 또는 .shp 파일의 전체 URL을 문자열로 전달하면, 라이브러리가 내부적으로 데이터를 가져와 파싱한다. 이 방식은 서버에 저장된 데이터를 클라이언트에서 직접 로드할 때 유용하지만, CORS(Cross-Origin Resource Sharing) 정책에 의해 차단되지 않도록 서버 측 설정이 필요할 수 있다.9

import shp from 'shpjs';
import { FeatureCollection } from 'geojson';

async function parseFromUrl(url: string): Promise<void> {
try {
console.log(`Fetching and parsing from URL: ${url}`);
const geojson = await shp(url) as FeatureCollection;

console.log('Successfully parsed data from URL.');
console.log(`Number of features: ${geojson.features.length}`);
} catch (error) {
console.error('Error fetching or parsing data:', error);
}

}

// 예제 실행
parseFromUrl('https://example.com/data/my_shapefile.zip');

개별 파일 버퍼를 이용한 처리

드물지만 .zip 파일이 아닌 개별 파일의 버퍼를 가지고 있는 경우, 이들을 속성으로 갖는 객체를 shp 함수에 전달하여 파싱할 수 있다. 이 방법은 .cpg 파일을 명시적으로 지정하여 특정 문자 인코딩을 강제하거나, .prj 파일 없이 기본 좌표계를 가정해야 할 때 유용하다.9

import * as fs from 'fs/promises';
import shp from 'shpjs';
import { FeatureCollection } from 'geojson';

async function parseFromIndividualBuffers(): Promise<void> {
try {
const shpBuffer = await fs.readFile('data/my_shapefile.shp');
const dbfBuffer = await fs.readFile('data/my_shapefile.dbf');
//.prj와.cpg는 선택 사항
const prjBuffer = await fs.readFile('data/my_shapefile.prj');
const cpgBuffer = await fs.readFile('data/my_shapefile.cpg');
const geojson = await shp({
shp: shpBuffer,
dbf: dbfBuffer,
prj: prjBuffer,
cpg: cpgBuffer
}) as FeatureCollection;
console.log('Successfully parsed from individual buffers.');
console.log(`Number of features: ${geojson.features.length}`);
} catch (error) {
console.error('Error parsing from buffers:', error);
}
}
parseFromIndividualBuffers();

4.3 GeoJSON 변환 및 결과 데이터 구조

shp 함수는 성공적으로 파싱을 완료하면 Promise를 통해 GeoJSON FeatureCollection 객체를 반환한다. 만약 입력된 ZIP 파일 내에 여러 개의 Shapefile 세트가 포함되어 있다면, FeatureCollection 객체들의 배열이 반환될 수 있다.9 반환된 객체에는 원본 파일의 기본 이름을 나타내는

fileName 속성이 추가로 포함될 수 있다.9

TypeScript 환경에서는 @types/geojson 패키지에서 제공하는 FeatureCollection, Feature, Geometry 등의 인터페이스를 사용하여 이 결과값을 강력한 타입으로 다룰 수 있다. 이를 통해 features 배열이나 각 피처의 properties, geometry 객체에 접근할 때 코드 편집기의 자동 완성 기능과 컴파일 시점의 타입 체크를 통해 개발 생산성과 코드 안정성을 크게 향상시킬 수 있다.

5. 변환된 GeoJSON 데이터의 활용

Shapefile을 GeoJSON으로 변환하는 진정한 가치는 TypeScript의 강력한 타입 시스템을 활용하여 이 데이터를 안전하고 표현력 있게 다룰 때 발현된다. GeoJSON은 지리공간 데이터의 이질적인 특성(다양한 지오메트리 타입)을 내포하고 있으며, TypeScript는 이를 효과적으로 처리할 수 있는 기능을 제공한다.

5.1 GeoJSON 구조와 타입-세이프 접근

• GeoJSON (RFC 7946) 구조: shpjs로부터 반환된 데이터는 대부분 GeoJSON 표준 19을 따르는

FeatureCollection 타입의 단일 객체다. 이 객체는 최상위에 type: "FeatureCollection" 멤버와 features라는 이름의 배열 멤버를 가진다.19

• features 배열: 이 배열의 각 요소는 Feature 객체다. Feature 객체는 type: "Feature", 지오메트리 정보를 담은 geometry 객체, 그리고 속성 정보를 담은 properties 객체를 핵심 멤버로 가진다.19

• geometry 객체: 지오메트리의 유형을 나타내는 type (예: “Point”, “Polygon”)과 실제 좌표 데이터를 담은 coordinates 배열을 포함한다. coordinates 배열의 중첩 구조는 type에 따라 달라진다. 예를 들어, Point는 단일 위치 [longitude, latitude]를, Polygon은 외부 링과 내부 링(홀)을 나타내는 3차원 배열 [[[lon, lat],...]] 구조를 가진다.19

• properties 객체: 원본 .dbf 파일의 한 행에 해당하는 속성 데이터를 담고 있는 일반 JSON 객체다. 객체의 키(key)는 .dbf의 필드 이름에 해당하고, 값(value)은 해당 레코드의 값이다.19

• TypeScript를 이용한 데이터 순회 및 타입 가드 활용:

FeatureCollection에 포함된 지오메트리는 Point, Polygon 등 다양할 수 있으므로, geometry 객체는 본질적으로 이질적인(heterogeneous) 데이터 구조다. 일반 JavaScript에서는 feature.geometry.type을 확인하는 방어적인 코드를 작성해야 하며, 실수로 잘못된 coordinates 구조에 접근할 위험이 있다.

TypeScript는 이러한 문제를 ’구별된 유니온(discriminated unions)’과 ’타입 가드(type guards)’를 통해 우아하게 해결한다. @types/geojson의 Geometry 타입은 Point | LineString | Polygon |... 과 같은 유니온 타입으로 정의되어 있으며, 각 멤버는 type 속성에 고유한 리터럴 타입(예: "Point")을 가지고 있다. 이것이 구별자(discriminant) 역할을 한다.

개발자가 if (feature.geometry.type === 'Polygon')과 같은 조건문을 작성하면, TypeScript 컴파일러는 해당 if 블록 내에서 feature.geometry의 타입을 더 구체적인 Polygon 타입으로 좁혀서 추론(type narrowing)한다. 이 강력한 기능을 통해 coordinates 속성에 접근할 때 완벽한 타입 안전성을 보장받을 수 있다.

다음은 타입 가드를 활용하여 GeoJSON 데이터를 안전하게 처리하는 예제 코드다.

import { FeatureCollection, Feature, Geometry } from 'geojson';

function processGeoJson(data: FeatureCollection): void {
console.log(`Processing ${data.features.length} features.`);
for (const feature of data.features) {
const properties = feature.properties;
const geometry = feature.geometry;
if (properties) {
console.log(`Feature Properties:`, properties);
}
if (geometry) {
// 타입 가드를 활용한 지오메트리 타입별 처리
switch (geometry.type) {
case 'Point':
// 이 블록 안에서 `geometry`는 `Point` 타입으로 추론됨
console.log(`Found a Point at: ${geometry.coordinates}`);
break;
case 'Polygon':
// 이 블록 안에서 `geometry`는 `Polygon` 타입으로 추론됨
const exteriorRing = geometry.coordinates;
console.log(`Found a Polygon with ${exteriorRing.length} vertices in its exterior ring.`);
break;
case 'MultiPolygon':
// 이 블록 안에서 `geometry`는 `MultiPolygon` 타입으로 추론됨
console.log(`Found a MultiPolygon with ${geometry.coordinates.length} polygons.`);
break;
// LineString, MultiPoint, MultiLineString 등 다른 타입에 대한 처리 추가
default:
console.log(`Unsupported geometry type: ${geometry.type}`);
}
}
}
}
// shpjs로 변환된 geojson 객체를 이 함수에 전달하여 사용
// const geojson: FeatureCollection = await shp(zipBuffer);
// processGeoJson(geojson);

이 패턴은 코드의 가독성을 높일 뿐만 아니라, 런타임 에러를 컴파일 타임에 방지하여 매우 견고하고 유지보수하기 쉬운 지리정보 처리 코드를 작성할 수 있게 한다.

5.2 데이터 후처리 및 분석

GeoJSON으로 변환된 데이터는 다양한 라이브러리와 손쉽게 연동하여 추가적인 가공 및 분석을 수행할 수 있다.

• 속성 데이터 필터링 및 변환: JavaScript의 표준 배열 메서드를 활용하여 데이터를 쉽게 조작할 수 있다. 예를 들어, 특정 인구수 이상의 도시만 필터링하거나, 필요한 속성만 추출하여 새로운 properties 객체를 만들 수 있다.

const filteredFeatures = geojson.features.filter(feature =>
feature.properties && feature.properties.population > 1000000
);

const simplifiedFeatures = geojson.features.map(feature => ({
...feature,
properties: {
name: feature.properties?.name,
country: feature.properties?.country_code
}
}));

• 공간 분석 라이브러리 연동: 변환된 GeoJSON은 turf.js와 같은 강력한 클라이언트 측 공간 분석 라이브러리의 표준 입력 형식이다.22 이를 통해 복잡한 GIS 연산을 브라우저나 Node.js 환경에서 직접 수행할 수 있다.

• 폴리곤 면적 계산: turf.area(polygonFeature)

• 두 지점 간의 거리 계산: turf.distance(point1, point2)

• 특정 지점 주변의 버퍼(buffer) 생성: turf.buffer(pointFeature, 5, { units: 'kilometers' })

• 두 지오메트리의 교차 영역(intersection) 계산: turf.intersect(polygon1, polygon2)

• 웹 매핑 시각화: Leaflet 21, Google Maps API 23, OpenLayers 24, Mapbox GL JS 등 거의 모든 현대 웹 매핑 라이브러리는 GeoJSON을 기본 데이터 소스로 지원한다. 변환된

FeatureCollection 객체를 라이브러리의 GeoJSON 레이어에 전달하기만 하면 손쉽게 지도 위에 데이터를 시각화하고 상호작용을 추가할 수 있다.

6. 고급 주제 및 실제적 고려사항

Shapefile을 안정적으로 다루기 위해서는 기본적인 파싱 방법을 넘어, 데이터의 무결성과 정확성에 영향을 미치는 몇 가지 중요한 요소들을 고려해야 한다. 이는 Shapefile 포맷의 사양이 남긴 “회색 지대“에서 비롯된 문제들이다.

6.1 문자 인코딩 문제와 .cpg 파일

.dbf 파일의 사양에는 문자 인코딩 정보를 명시하는 표준적인 방법이 포함되어 있지 않다.1 이로 인해 한글이나 다른 비-ASCII 문자가 포함된 속성 데이터를 파싱할 때 글자가 깨지는 문제가 빈번하게 발생한다. 이 문제를 해결하기 위해 사실상의 표준으로 자리 잡은 것이.cpg 파일이다.

.cpg 파일은 .dbf 파일에 사용된 문자 인코딩의 코드 페이지(예: UTF-8, CP949, EUC-KR)를 명시하는 단순한 텍스트 파일이다.5 예를 들어, 파일 내용이 UTF-8이라면 해당 .dbf 파일은 UTF-8로 인코딩되었음을 의미한다.

shpjs와 같은 최신 라이브러리들은 이 .cpg 파일의 존재를 인식한다. ZIP 아카이브에 .cpg 파일이 포함되어 있거나, 개별 버퍼로 명시적으로 제공될 경우, 라이브러리는 해당 인코딩을 사용하여 .dbf 파일의 바이트 스트림을 올바르게 문자열로 디코딩한다.10 따라서, 다국어 속성 데이터의 무결성을 보장하기 위해서는 원본 데이터를 생성하거나 전달받을 때 반드시 .cpg 파일을 함께 포함하는 것이 매우 중요하다.

6.2 좌표계 정보 처리와 .prj 파일

Shapefile의 핵심 구성 요소는 좌표 데이터 자체에 대한 정보만 담고 있을 뿐, 그 좌표가 지구상의 어느 위치를 기준으로 측정되었는지에 대한 정보, 즉 좌표 참조 시스템(Coordinate Reference System, CRS) 정보는 포함하지 않는다. 이 정보는 .prj라는 확장자를 가진 별도의 파일에 WKT(Well-Known Text) 형식으로 저장된다.5

반면, 우리가 목표로 하는 GeoJSON 포맷의 표준인 RFC 7946은 모든 좌표가 WGS 84 (EPSG:4326) 지리 좌표계(경위도)를 사용한다고 명시적으로 규정하고 있다.19 따라서, 원본 Shapefile이 한국에서 흔히 사용되는 UTM-K (EPSG:5179)나 Bessel TM (EPSG:2097)과 같은 투영 좌표계를 사용한다면, GeoJSON으로 올바르게 변환하기 위해서는 반드시 WGS 84로의 재투영(reprojection) 과정이 필요하다.

shpjs는 .prj 파일이 존재할 경우, 그 내용을 읽어 원본 좌표계를 파악하고 WGS 84로 재투영을 시도한다. 이를 위해 내부적으로 proj4js와 같은 좌표 변환 라이브러리를 활용할 가능성이 높다.9 이 기능 덕분에 개발자는 대부분의 경우 좌표계 문제에 대해 신경 쓰지 않아도 된다.

그러나 shapefile 라이브러리와 같이 재투영을 지원하지 않는 도구를 사용하거나, .prj 파일이 누락된 데이터를 처리해야 하는 경우에는 문제가 복잡해진다. 이 경우, 개발자는 데이터의 출처를 통해 원본 좌표계를 파악하고, proj4js와 같은 외부 라이브러리를 사용하여 변환된 GeoJSON의 모든 좌표를 직접 순회하며 변환하는 로직을 구현해야 한다.

이러한 .prj와 .cpg 파일의 “선택적” 특성은 Shapefile 포맷의 가장 큰 약점 중 하나이다. 데이터가 그 의미를 해석하는 데 필수적인 메타데이터와 쉽게 분리될 수 있기 때문이다. 따라서 전문가 수준의 접근 방식은 단순히 라이브러리 함수를 호출하는 것을 넘어, 방어적 프로그래밍 자세를 취하는 것을 포함한다. 애플리케이션 로직은 파싱 전에 .prj 파일의 존재 여부를 확인하고, 만약 없다면 데이터를 거부하거나 명확한 경고와 함께 기본값(예: WGS 84)을 가정하는 정책을 수립해야 한다. 이는 데이터의 오용을 막고 시스템의 신뢰성을 높이는 중요한 단계이다.

6.3 Shapefile 포맷의 한계와 대안 포맷

Shapefile은 지난 수십 년간 지리정보 분야에서 중요한 역할을 해왔지만, 현대적인 데이터 요구사항에 비추어 볼 때 명백한 한계를 가지고 있다.

• 한계점 요약:

• 취약한 다중 파일 구조: 데이터 무결성 관리가 어렵다.6

• 2GB 파일 크기 제한: 대용량 벡터 데이터셋을 저장할 수 없다.1

• 제한적인 필드 명명 규칙: 필드 이름은 최대 10자의 ASCII 문자로 제한된다.7

• 제한된 필드 타입: 날짜와 시간을 함께 저장하는 타입이 없고, 부동소수점 숫자는 텍스트로 저장될 때 반올림 오류가 발생할 수 있다.1

• 토폴로지 부재: 인접한 폴리곤이 경계를 공유하는 관계 등을 표현할 수 없어, 네트워크 분석이나 경계선 정리 같은 고급 분석에 제약이 있다.1

• 비공식적인 확장: 3D나 측정값(M)과 같은 차원은 나중에 추가되었으며, 모든 소프트웨어에서 일관되게 지원되지 않을 수 있다.6

이러한 한계로 인해, 많은 현대 GIS 프로젝트에서는 다음과 같은 대안 포맷을 채택하고 있다.

• GeoPackage (.gpkg): OGC(Open Geospatial Consortium) 표준으로, 단일 SQLite 데이터베이스 파일 안에 여러 벡터 및 래스터 레이어, 스타일 정보, 메타데이터 등을 모두 저장할 수 있다. 단일 파일 구조 덕분에 데이터 관리와 이동성이 매우 뛰어나다.6

• GeoJSON / TopoJSON: 웹 환경에 최적화된 경량 텍스트 기반 포맷이다. 특히 TopoJSON은 공유 경계(arc)를 한 번만 저장하여 위상 관계를 표현하고 파일 크기를 획기적으로 줄일 수 있어 웹 매핑에 널리 사용된다.26

• PostGIS: PostgreSQL 관계형 데이터베이스의 공간 데이터 확장 기능이다. 대규모 데이터의 저장, 인덱싱, 복잡한 공간 쿼리 및 분석에서 매우 강력한 성능을 제공하며, 엔터프라이즈급 GIS 시스템의 백엔드로 널리 사용된다.6

7. 결론

본 안내서는 TypeScript 개발 환경에서 ESRI Shapefile이라는 레거시 지리공간 데이터 포맷을 다루기 위한 심층적인 기술 가이드를 제공했다. Shapefile을 구성하는 세 가지 핵심 파일(.shp, .shx, .dbf)의 복잡한 바이너리 구조, 특히 현대 파서 구현에 있어 주요 장애물인 혼합 엔디안 아키텍처를 상세히 분석했다. 또한, JavaScript 생태계에 존재하는 주요 파싱 라이브러리인 shpjs, shapefile, shp-to-geojson의 API 설계, 기능, 성능, 그리고 TypeScript 지원 수준을 비교하여 각기 다른 프로젝트 요구사항에 맞는 최적의 도구를 선택할 수 있는 기준을 제시했다.

분석 결과, 대부분의 웹 기반 및 Node.js 애플리케이션 환경에서는 shpjs 라이브러리를 사용하여 Shapefile 구성 요소 전체를 포함한 ZIP 아카이브를 GeoJSON FeatureCollection으로 직접 변환하는 것이 가장 효율적이고 안정적인 워크플로우임이 확인되었다. 이 접근 방식은 Shapefile의 다루기 힘든 다중 파일 구조를 효과적으로 추상화하고, 개발자가 데이터의 내용 자체에 집중할 수 있도록 한다. 특히, 데이터의 정확성을 보장하기 위해 좌표계 정보를 담은 .prj 파일과 문자 인코딩을 명시하는 .cpg 파일을 원본 데이터에 반드시 포함하여 함께 처리하는 것이 중요하다.

변환된 GeoJSON 데이터는 @types/geojson 타입 정의를 통해 TypeScript의 정적 타입 시스템 안에서 완벽하게 다룰 수 있다. Geometry 타입을 구별된 유니온으로 인식하고, switch 문과 같은 제어 흐름 분석을 통해 타입을 좁히는 타입 가드 패턴을 활용하면, 다양한 지오메트리 타입을 처리하는 코드를 런타임 에러 없이 안전하고 명료하게 작성할 수 있다. 이는 복잡한 지리정보 데이터를 다루는 애플리케이션의 안정성과 유지보수성을 극적으로 향상시키는 TypeScript의 핵심적인 가치이다.

Shapefile은 방대한 양의 기존 데이터 덕분에 앞으로도 상당 기간 데이터 교환 포맷으로서의 명맥을 유지할 것이다. 그러나 2GB 크기 제한, 취약한 파일 구조, 제한적인 데이터 모델 등 그 내재적 한계는 명확하다. 따라서 장기적인 관점에서 새로운 시스템을 구축할 때는 단일 파일 구조로 데이터 무결성을 보장하고, 풍부한 데이터 타입을 지원하며, 대용량 처리에 용이한 GeoPackage나 PostGIS와 같은 현대적인 포맷을 우선적으로 고려해야 한다. TypeScript 개발자는 Shapefile을 능숙하게 처리하여 레거시 데이터를 통합하는 능력을 갖추는 동시에, 이러한 최신 기술 스택을 적극적으로 도입하여 더 확장 가능하고 견고한 차세대 지리정보 시스템을 구축할 준비를 해야 할 것이다.